Skip to content

feat(confsearch): search engine, checkpoint/resume, results and exports (P2) - #64

Merged
hydrogen1222 merged 7 commits into
mainfrom
confsearch/p2-engine
Oct 26, 2026
Merged

hydrogen1222 merged 7 commits into
mainfrom
confsearch/p2-engine

Conversation

@hydrogen1222

@hydrogen1222 hydrogen1222 commented Oct 25, 2026 •

Copy link
Copy Markdown
Owner

Tracking: #61
Implements spec revision 4, phase P2.

What this does

Adds the search engine:

  • quench.py: fixed-cell FIRE on R with only FixAtoms, per-step finite and
    raw-force gates, quench_failed / quench_not_converged as outcomes, and
    refine().
  • engine.py: the section 7.1 schedule (start quench -> round-robin cycles ->
    consolidation -> refinement -> ranking), section 7.2 mobile sets, the section
    7.3 cycle (Maxwell-Boltzmann over the mobile DOF with zero fixed momenta,
    Langevin hold, linear cool ramp with set_temperature every
    cs_ramp_interval, snapshot frames, per-step safety, early integrity abort,
    end-of-cycle Metropolis with the uniform draw taken every eligible proposal),
    section 7.5 SeedSequence streams, raw raw/replica_RRR/cycle_CCC/ output
    through AsyncMDOutputWriter with the unchanged MD_CSV_HEADER plus
    cycle.json, and the section 7.1 failed_start handling.
  • checkpoint.py: atomic JSON checkpoints after every unit, the resume
    fingerprint (version, revisions, model, input hashes, regions, seed, every
    option except output/verbosity), key-level diffing on refusal, and
    incomplete-attempt archiving that never deletes raw files.
  • results.py: diagnostics/discovery.csv, saturation diagnostics ("lowest
    found", never "global minimum"), baseline vs search, the section 8.5
    warnings, top-K refinement, ranking in separate refined/unrefined tables,
    artifacts.json and the section 10.5 exports (POSCAR with selective dynamics,
    structure.extxyz, cp2k_coord.xyz, cp2k_cell.inc,
    cp2k_fixed_atoms.inc, minimum.json) with the slab wrapped and the
    adsorbate made whole under MIC.

What it does NOT do yet

  • No config keys, CLI, API or docs page (P3); the engine is driven from Python
    with hand-built PreparedStart objects.
  • No extend/merge/queue/TUI (P4/P5).
  • The end-to-end tests use the synthetic egg-crate model; a real backend
    campaign is P5.

Tests run and results

CUDA_VISIBLE_DEVICES="" .venv-dev/bin/python -m pytest -q
CUDA_VISIBLE_DEVICES="" .venv-dev/bin/python -m pytest tests/mliport/mliport/confsearch tests/mliport/mliport/test_confsearch_validation_suite.py -q
.venv-dev/bin/ruff check mliport/mliport tests scripts validation/science/scripts
.venv-dev/bin/ruff format --check mliport/mliport tests scripts validation/science/scripts
.venv-dev/bin/python scripts/check_repository_hygiene.py
  • 1569 passed, 33 skipped; tests/mliport/mliport/confsearch/test_engine.py
    is 14 tests.
  • End-to-end on the egg-crate model: every known minimum found to 1e-6 eV,
    same-basin quenches merged through G, fixed atoms never move, the
    temperature ramp equals the documented linear schedule, force / non-finite /
    integrity aborts are recorded and the search continues.
  • Two runs with one seed produce identical rankings and file sets; an
    interrupted run resumed from its checkpoint reproduces the uninterrupted
    ranking exactly; exports re-read equal to the minimum up to lattice
    translations.

Deviations from spec

  • build_results marks a run failed only when it had replicas and none
    survived (a merge has none), which matches section 7.1 but is stricter than
    "no surviving replica" read literally.
  • A quench whose energy is not finite stores null for that minimum's measured
    distances (JSON has no NaN) instead of a NaN sentinel.
  • The raw MD CSV keeps the MD contract and writes phase = hold|cool; the
    target-temperature schedule is recorded in cycle.json, as specified.
  • Tests: the engine tests were written before the last fixes they drove
    (checkpoint from_dict, fingerprint recomputation on resume, NaN handling),
    so those fixes were red-first; the initial engine skeleton and the results/
    exports module were implemented and then covered by the same commit's tests.

Revision 5 follow-up (review of this PR)

  • Refinement is honoured (spec 10.1/10.3): a refinement replaces the quench
    result only when it converged and its status is still rankable. An
    unconverged refinement keeps the quench result and is flagged; a refinement
    that changed to a non-rankable status leaves the ranking with a recorded
    reason. The refined set is re-deduplicated with the §9.3 rule (merged entries
    keep the summed hit counts, the union of replicas and the earliest
    first-found record), ranking and top/rank_001 follow the refined energy,
    and refined/unrefined energies are never interleaved (each table has its own
    best; ranking.best_energy_source says which).
  • Abort frames are never quenched (spec 7.3): the integrity check runs before
    a snapshot is kept, the force abort raises before the snapshot is kept, and
    the except clause no longer appends the abort frame, so an integrity-abort
    frame is not quenched twice; the end-of-cycle frame gets the same integrity
    check.
  • quench() cannot crash the search: a calculator that raises on a bad
    geometry yields quench_failed.
  • Diagnostics: top_k_never_reached_by_start_quench means "no member has
    a start origin"; first_found_fraction uses first_found_quench_index.
  • Outputs (spec 11.1): minima/all_minima.extxyz holds every quench result
    of every status with provenance, and minima/registry.json holds the registry.
  • New tests/mliport/mliport/confsearch/test_refinement.py (6 tests) covers
    reordering, merging, unconverged refinement, status change, the minima
    directory and the member-based diagnostics.

Full suite on CPU (rebased stack): 1632 passed, 33 skipped; lint/format and
the repository hygiene check clean; CI green.


Revision 6 follow-up (second review of this PR)

  • A candidate whose refinement did not converge is still exported (spec rev 6
    §10.3).
    It is written as top/unrefined_NNN/ with its quench geometry and
    energy, flagged (refined: false, refinement_failed: true in
    artifacts.json), next to the refined ranks, and a warning names it. This
    closes the "silent deletion" failure mode §9.3 warns about: a floppy chain that
    cannot reach 0.02 eV/A may still be the lowest quench minimum.
  • A refined entry's flags come from the refined classification, not from the
    quench representative (chemisorbed/physisorbed and the far-field slab flag can
    change during refinement).
  • Tests: two new cases in test_refinement.py (the failed-refinement candidate
    is exported with its quench energy/geometry and produces a warning; the refined
    entry's flags follow the refined classification).

Full suite on CPU: 1639 passed, 33 skipped; lint/format/hygiene clean; CI
green.

Tracking: #61 (spec revision 4, phase P1)
Part of the MD-based configuration search feature.

What was missing: mliport/confsearch/ did not exist, so nothing could prepare
starts, describe a minimum, or deduplicate quench results.

What this adds (calculator-free, synthetic-structure testable):
- options.py: frozen ConfsearchOptions with every section 12.3 cross-key rule
  (mode A/B exclusivity, exact integer step conversions with nearest valid
  values, break > bond scale, binwidth <= sigma/2, v1 non-goals rejected by
  name), index_spec.py: the 0-based "0,5,7-9" parser with compression.
- regions.py: A/S/F/R resolution, FixScaled/FixCom rejection, cs_fix_below,
  the +z surface convention, slab contiguity, one-sided adsorption, non-ionic
  adsorbate connectivity, the H/timestep gate and the section 7.2 mobile sets.
- graphs.py: covalent graphs from ase.data.covalent_radii, ionic exclusion,
  the MD break-scale check, chemisorption flags, slab-rearrangement flags and
  the section 8.2 status rules in order.
- fingerprint.py: focused Oganov-Valle with ASE's discretisation (spec 9.2
  revision 3): nbins = ceil(rcut/Delta), bin radius (k+1)Delta, erf bin
  smearing renormalised to 1, 4 pi r^2 Delta and N_beta/V normalisation,
  ordered species keys and the section 9.2 weights.
- registry.py: delta-E AND (G OR D) matching (spec 9.3 revision 4), the direct
  geometric identity G with cs_dedup_geom_tol (disabled and recorded when F is
  empty), smallest (not G, D) selection, per-status registries, representative
  update and the section 9.5 consolidation pass.
- placement.py: centroiding, Shoemake rotations, contact and anchored placement
  solved by bisection on element-pair covalent-radii ratios, anchor targets,
  per-reason rejection counts and the recorded placement provenance.

Deviations from the letter of section 9.2, both required by section 9.2 itself
and documented in the module docstring:
- self-image pairs are enumerated explicitly because ASE's neighbor_list
  returns an orientation-dependent subset of them (48 vs 72 pairs on a 4x4x20 A
  slab before/after a rigid rotation, while the 350 cross pairs are identical);
- pair distances are rounded to 1e-9 A before the bin division because a
  distance at a decimal multiple of Delta (e.g. a 0.96 A O-H bond) otherwise
  flips its whole 21-bin smearing window under a rigid rotation.
The strict ASE known-answer tests still pass to 1e-10 on non-boundary
geometries (per-bin arrays, F_ab == F_ba, collapsed D), and scipy/matplotlib
were added to the dev extra so they run in CI instead of skipping.

Calibration (spec 13.2 revision 4, geometry-labelled pairs on the repository's
LGPS structure, pinned as a regression test):
  same basin 25 pairs (G), 11 documented false splits (0.20-0.5 A);
  distinct sites/conformers 63 pairs, min D = 8.5e-4 at sigma = 0.20;
  equivalent pairs (rigid slab map + CH3 permutation) all merge (D ~ 0).
Shipped defaults: cs_fp_sigma = 0.20, cs_dedup_fp_tol = 0.0004 (zero false
merges with a factor-2 margin), cs_dedup_geom_tol = 0.20 A.

DATA IMPACT: no scientific record invalidated (no existing workflow changed).
New defaults are recorded here and in the calibration test; the P2 engine will
re-run the same sweep with real quenches at cs_quench_fmax. Full suite on CPU:
1555 passed, 33 skipped.

@hydrogen1222 hydrogen1222 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review (spec rev 5) — P2: changes requested

The cycle (MB over mobile DOF with zero fixed momenta, Langevin hold, linear ramp via set_temperature, snapshot quenches, Metropolis with aligned draws), RNG streams and checkpoint/restore are correct. Requested changes, most important first:

1. Refinement / ranking (§10.1, §10.3) — blocking. In results.build_results (~L383–430):

  • ranked_energies uses the refinement energy unconditionally, also when the refinement is quench_failed (energy may be NaN), not converged, or changed status (e.g. now reacted/desorbed). Spec: an unconverged refinement keeps the quench result and is flagged; a status change must be honoured (a refined minimum that is no longer rankable leaves the ranking, with a record why).
  • Ranking entries and export directories follow quench-energy order (rankable), not refined energy, so top/rank_001 is not necessarily the lowest refined structure.
  • The refined set is not re-deduplicated (§10.3), so two uniques that refine into the same minimum are both exported.
  • best_energy and the export window mix refined (fmax 0.02) and unrefined (fmax 0.05) energies; spec says never interleave them. Rank refined entries among themselves; report unrefined separately.
    Tests: a synthetic case where refinement (a) lowers the order of two candidates, (b) merges two candidates, (c) fails, (d) changes status.

2. Aborted MD frames are quenched (§7.3 step 9). engine.py ~L641 appends exc.frame to snapshots. A force-abort frame (|F| > 20 eV/Å) or a non-finite frame is then quenched, and an integrity-abort frame is quenched twice (it was appended at L607 before _check_md_integrity raised). This inflates reacted/quench_failed counts, which feed the §8.5 warnings and the discovery curve. Quench only snapshots taken before the stop; keep the abort frame in the raw trajectory only.

3. End-of-cycle integrity check missing (§7.3 step 7). _check_md_integrity runs only at snapshot steps; also run it on the final frame.

4. quench() can crash the search. quench.py L124 calls work.get_potential_energy() outside any try; a calculator that raises on a bad geometry turns a quench_failed outcome into an uncaught exception. Wrap it.

5. Diagnostics definitions.

  • _baseline_report: "top-K never reached by any start quench" must mean unique minima with no member whose origin is start — not "representative not from start and below the baseline best".
  • best_first_found_fraction (L271) and first_found_fraction (L152) use the representative's quench_index; use first_found_quench_index.

6. Missing outputs (§11.1). minima/all_minima.extxyz (every quench result, all statuses) and minima/registry.json are never written; members' geometries are therefore lost except representatives. Write them.

🤖 Generated with Claude Code


Generated by Claude Code

… §5.2)

Tracking: #61 (spec revision 5, PR #63 review)
Addresses review items 1-3 on #63.

- Anchored placement now solves the height against the anchor's **partner
  set**: the non-ionic slab atoms by default, or exactly the
  `cs_place_anchor_targets` elements when that option is set.  Previously the
  minimum `q` was taken over every slab atom, so an anchor O could be placed at
  1.1x the O+Li radii sum from a lithium: an ionic contact that §8.1/§8.2 then
  classify as physisorbed, i.e. the "chemisorption-first" start was not
  chemisorbed.  `anchor_partner_indices()` fails closed when the slab has no
  partner at all (all-ionic slab without targets).
- Tests: a Li-terminated slab must bond the O anchor to a sulfur (and the
  recomputed min q over non-ionic atoms equals `cs_place_anchor_scale`),
  `cs_place_anchor_targets="Li"` is the explicit opt-in to an ionic partner, and
  an all-ionic slab without targets is refused.
- `fingerprint.py` docstring rewritten for revisions 3-5: ASE discretisation,
  the withdrawn pre-rev-3 point-sampled formula, the strict per-bin 1e-10
  known-answer test that never skips (ASE 3.26 oracle when the ASE 3.29 shim is
  in place), and the self-image paragraph reworded as a cutoff-boundary effect
  (images at exactly rcut) rather than an ASE defect.
- `placement.py` documents that `min q` is monotone except in the descent
  branch, where atoms can end up slightly below the slab top.
- `options.py` and the calibration test now state the P1 calibration's known
  limitations (bulk-cell geometry, perturbations instead of quenches, exact
  rigid images) and point at a real-slab/real-model recalibration as a P5
  validation item.

DATA IMPACT: no scientific record invalidated. Placement semantics change only
for anchored starts on slabs containing ionic species; the shipped defaults and
the fingerprint/dedup behaviour are unchanged. Full confsearch suite on CPU:
112 passed.
…puts (spec rev 5 §10/§11.1)

Tracking: #61 (spec revision 5, PR #64 review)
Addresses all six review items on #64.

Ranking and refinement (spec 10.1/10.3):
- a refinement replaces the quench result only when it converged **and** its
  classification is still rankable; an unconverged refinement keeps the quench
  result and is flagged (`refinement_failed`, note
  `refinement_not_converged`); a refinement that changed to a non-rankable
  status leaves the ranking entirely with a recorded reason
  (`refinement_changed_status`);
- the refined set is re-deduplicated with the section 9.3 rule through a scratch
  registry, and a merged entry keeps the summed hit counts, the union of
  replicas and the earliest first-found record;
- ranking and export directories follow the **refined** energy, so
  `top/rank_001` is the lowest refined structure;
- refined and unrefined energies are never interleaved: each table has its own
  best energy, the export window is relative to the refined best, and
  `ranking.best_energy_source` says which table the reported best came from.

Engine (spec 7.3):
- abort frames are never quenched: the observer checks the integrity *before*
  keeping a snapshot, the force abort raises before the snapshot is kept, and
  the `except` clause no longer appends the abort frame, so an
  integrity-abort frame is not quenched twice;
- the end-of-cycle frame gets the same early integrity check as the hold-phase
  snapshots;
- `quench()` no longer lets a calculator that raises on a bad geometry escape as
  an uncaught exception; the outcome is `quench_failed`.

Diagnostics (spec 10.2/10.4):
- `top_k_never_reached_by_start_quench` now means "no *member* has a start
  origin" (merged refined entries are checked through all their source ids);
- `first_found_fraction` and `best_first_found_fraction` use the unique's
  `first_found_quench_index`, not the representative's own quench index.

Outputs (spec 11.1):
- `minima/all_minima.extxyz` now holds every quench result of every status with
  its provenance (unique id, record id, status, flags, energy, fmax, steps,
  quench index, cumulative MD ps, origin), and `minima/registry.json` holds the
  registry.  Non-finite energies are omitted from the frame info because extxyz
  cannot carry NaN.

Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers
reordering, merging, unconverged refinement, status change, the minima directory
and the member-based diagnostics.  Full confsearch suite on CPU: 132 passed.

DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the
`minima/` contents change; runs are re-ranked from their stored quench results.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…puts (spec rev 5 §10/§11.1)

Tracking: #61 (spec revision 5, PR #64 review)
Addresses all six review items on #64.

Ranking and refinement (spec 10.1/10.3):
- a refinement replaces the quench result only when it converged **and** its
  classification is still rankable; an unconverged refinement keeps the quench
  result and is flagged (`refinement_failed`, note
  `refinement_not_converged`); a refinement that changed to a non-rankable
  status leaves the ranking entirely with a recorded reason
  (`refinement_changed_status`);
- the refined set is re-deduplicated with the section 9.3 rule through a scratch
  registry, and a merged entry keeps the summed hit counts, the union of
  replicas and the earliest first-found record;
- ranking and export directories follow the **refined** energy, so
  `top/rank_001` is the lowest refined structure;
- refined and unrefined energies are never interleaved: each table has its own
  best energy, the export window is relative to the refined best, and
  `ranking.best_energy_source` says which table the reported best came from.

Engine (spec 7.3):
- abort frames are never quenched: the observer checks the integrity *before*
  keeping a snapshot, the force abort raises before the snapshot is kept, and
  the `except` clause no longer appends the abort frame, so an
  integrity-abort frame is not quenched twice;
- the end-of-cycle frame gets the same early integrity check as the hold-phase
  snapshots;
- `quench()` no longer lets a calculator that raises on a bad geometry escape as
  an uncaught exception; the outcome is `quench_failed`.

Diagnostics (spec 10.2/10.4):
- `top_k_never_reached_by_start_quench` now means "no *member* has a start
  origin" (merged refined entries are checked through all their source ids);
- `first_found_fraction` and `best_first_found_fraction` use the unique's
  `first_found_quench_index`, not the representative's own quench index.

Outputs (spec 11.1):
- `minima/all_minima.extxyz` now holds every quench result of every status with
  its provenance (unique id, record id, status, flags, energy, fmax, steps,
  quench index, cumulative MD ps, origin), and `minima/registry.json` holds the
  registry.  Non-finite energies are omitted from the frame info because extxyz
  cannot carry NaN.

Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers
reordering, merging, unconverged refinement, status change, the minima directory
and the member-based diagnostics.  Full confsearch suite on CPU: 132 passed.

DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the
`minima/` contents change; runs are re-ranked from their stored quench results.
hydrogen1222 added a commit that referenced this pull request Oct 25, 2026
…puts (spec rev 5 §10/§11.1)

Tracking: #61 (spec revision 5, PR #64 review)
Addresses all six review items on #64.

Ranking and refinement (spec 10.1/10.3):
- a refinement replaces the quench result only when it converged **and** its
  classification is still rankable; an unconverged refinement keeps the quench
  result and is flagged (`refinement_failed`, note
  `refinement_not_converged`); a refinement that changed to a non-rankable
  status leaves the ranking entirely with a recorded reason
  (`refinement_changed_status`);
- the refined set is re-deduplicated with the section 9.3 rule through a scratch
  registry, and a merged entry keeps the summed hit counts, the union of
  replicas and the earliest first-found record;
- ranking and export directories follow the **refined** energy, so
  `top/rank_001` is the lowest refined structure;
- refined and unrefined energies are never interleaved: each table has its own
  best energy, the export window is relative to the refined best, and
  `ranking.best_energy_source` says which table the reported best came from.

Engine (spec 7.3):
- abort frames are never quenched: the observer checks the integrity *before*
  keeping a snapshot, the force abort raises before the snapshot is kept, and
  the `except` clause no longer appends the abort frame, so an
  integrity-abort frame is not quenched twice;
- the end-of-cycle frame gets the same early integrity check as the hold-phase
  snapshots;
- `quench()` no longer lets a calculator that raises on a bad geometry escape as
  an uncaught exception; the outcome is `quench_failed`.

Diagnostics (spec 10.2/10.4):
- `top_k_never_reached_by_start_quench` now means "no *member* has a start
  origin" (merged refined entries are checked through all their source ids);
- `first_found_fraction` and `best_first_found_fraction` use the unique's
  `first_found_quench_index`, not the representative's own quench index.

Outputs (spec 11.1):
- `minima/all_minima.extxyz` now holds every quench result of every status with
  its provenance (unique id, record id, status, flags, energy, fmax, steps,
  quench index, cumulative MD ps, origin), and `minima/registry.json` holds the
  registry.  Non-finite energies are omitted from the frame info because extxyz
  cannot carry NaN.

Tests: `tests/mliport/mliport/confsearch/test_refinement.py` (6 tests) covers
reordering, merging, unconverged refinement, status change, the minima directory
and the member-based diagnostics.  Full confsearch suite on CPU: 132 passed.

DATA IMPACT: no scientific record invalidated. Ranking/export ordering and the
`minima/` contents change; runs are re-ranked from their stored quench results.

@hydrogen1222 hydrogen1222 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Second review (spec rev 6) — P2: one should-fix

Items 1–6 of the first review are resolved: refinement only replaces a quench result when converged and still rankable, refined set re-deduplicated, ranking/exports by refined energy, no interleaving, abort frames no longer quenched, end-of-cycle integrity check, quench() robust, member-based baseline, first-found fraction, minima/ outputs. Good tests.

Remaining (spec rev 6 §10.3):

  1. When the refined table is non-empty, exports come only from it (results.py ~L674). A candidate inside the refinement window whose refinement did not converge (likely for floppy chains at fmax 0.02) is then not exported at all — possibly the lowest quench minimum — and only a refinement_notes entry records it. That is the "silent deletion" failure mode §9.3 warns about. Export such candidates as top/unrefined_NNN/ (quench geometry/energy, flagged) and add a warning naming them.
  2. _dedup_refined (L284) copies flags from the quench representative; after refinement the classification (chemisorbed/physisorbed, far-field flag) can differ. Use outcome.classification.flags.

🤖 Generated with Claude Code


Generated by Claude Code

Tracking: #61 (spec revision 6, second review of PR #63)

`place_molecule` computed `anchor_partner_indices(slab, options)` before it knew
whether an anchor had been requested, so **contact** placement on a slab without
non-ionic atoms (a Li-metal surface) was refused with an anchored-placement
error.  The partner set is now computed only when `cs_place_anchor` selects an
anchor (the objective and the final check assert it is present), which keeps the
revision 5 semantics for anchored starts.

Test: contact placement of OH on an all-Li slab succeeds, reports no anchor, and
still satisfies the contact rule (min q = cs_place_contact_scale to 1e-3).

DATA IMPACT: no scientific record invalidated. Anchored placement is unchanged;
contact placement on all-ionic slabs now works instead of failing closed.
Placement suite on CPU: 20 passed.
…ts (P2)

Tracking: #61 (spec revision 4, phase P2)
Part of the MD-based configuration search feature.

What was missing: P1 had no way to run a search - no MD cycles, no quench
pipeline, no Metropolis, no checkpointing and no results.

What this adds:
- quench.py: fixed-cell FIRE on R with only FixAtoms, per-step finite/force
  gates, quench_failed / quench_not_converged as outcomes, and refine().
- engine.py: the section 7.1 schedule (start quench -> round-robin cycles ->
  consolidation -> refinement -> ranking), the section 7.2 mobile sets, the
  section 7.3 cycle (Maxwell-Boltzmann over the mobile DOF with zero fixed
  momenta, Langevin hold, linear cool ramp with set_temperature every
  cs_ramp_interval, snapshot frames, per-step safety, early integrity abort,
  end-of-cycle Metropolis with the uniform draw taken every eligible proposal),
  the section 7.5 SeedSequence streams, raw/replica_RRR/cycle_CCC output through
  AsyncMDOutputWriter (unchanged MD_CSV_HEADER) and cycle.json, and the section
  7.1 failed_start handling.
- checkpoint.py: atomic JSON checkpoints after every unit, resume fingerprint
  (version, revisions, model, input hashes, regions, seed, every option except
  output/verbosity), key-level diffing on refusal, and incomplete-attempt
  archiving that never deletes raw files.
- results.py: discovery.csv, saturation diagnostics ("lowest found", never
  "global minimum"), baseline vs search, the section 8.5 warnings, top-K
  refinement, ranking in separate refined/unrefined tables, artifacts.json and
  the section 10.5 exports (POSCAR with selective dynamics, structure.extxyz,
  cp2k_coord.xyz, cp2k_cell.inc, cp2k_fixed_atoms.inc, minimum.json) with the
  slab wrapped and the adsorbate made whole under MIC.

Tests (spec 13.1/13.2): test-only synthetic calculators (egg-crate with three
known sites and exactly known energies, shallow-Morse bond breaking, direct
force, non-finite) plus end-to-end tests that the search finds every known
minimum to 1e-6 eV, that same-basin quenches merge through G, that fixed atoms
never move, that the temperature ramp is the documented linear schedule, that
force/non-finite/integrity aborts are recorded and the search continues, that
two runs with one seed are identical, that an interrupted run resumed from its
checkpoint reproduces the uninterrupted ranking exactly, and that exports
re-read equal to the minimum up to lattice translations.

DATA IMPACT: no scientific record invalidated. New outputs only. Full suite on
CPU: 1569 passed, 33 skipped.
…6 §10.3)

Tracking: #61 (spec revision 6, second review of PR #64)

- A candidate inside the refinement window whose refinement did not converge is
  no longer dropped from the DFT deliverable: it is exported as
  `top/unrefined_NNN/` with its **quench** geometry and energy (flagged
  `refined: false`, `refinement_failed: true` in `artifacts.json`), next to the
  refined ranks, and a warning names it.  This is the "silent deletion" failure
  mode section 9.3 warns about: a floppy chain that cannot reach 0.02 eV/A may
  still be the lowest quench minimum.
- A refined entry's `flags` now come from the **refined** classification instead
  of the quench representative (chemisorbed/physisorbed and the far-field slab
  flag can change during refinement).

Tests: two new cases in `test_refinement.py` (the failed-refinement candidate is
exported with its quench energy/geometry and produces a warning; the refined
entry's flags follow the refined classification).

DATA IMPACT: no scientific record invalidated. Exports gain candidates that were
previously missing; ranking order and energies are unchanged.
Confsearch suite on CPU: 134 passed.
Base automatically changed from confsearch/p1-core to main October 26, 2026 04:04
…nto P2

#63 was merged with 'Rebase and merge', which rewrote the P1 commits on main.
Their content is byte-identical to this branch's P1 base (41102c7), so this
merge keeps the branch tree unchanged and only records main as a parent,
which removes the add/add conflicts GitHub reported on #64.

DATA IMPACT: no scientific record invalidated (no file content changes).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017vVRW3uEnhYKFinpvqMysi
@hydrogen1222
hydrogen1222 marked this pull request as ready for review October 26, 2026 04:12
@hydrogen1222
hydrogen1222 merged commit 64dc407 into main Oct 26, 2026
11 checks passed
@hydrogen1222
hydrogen1222 deleted the confsearch/p2-engine branch October 26, 2026 04:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants